/*
 * @Description: MCP服务实例生成器
 *   核心功能：
 *   1. 创建基础MCP服务实例
 *   2. 批量注册工具模块
 *   3. 返回可立即使用的服务实例
 *
 * @Author: 莫若省
 * @date: 2025/9/2
 */

// 基础依赖导入
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
import { MCPToolInterface } from "../../types/index.js";

// 工具模块导入
import { TOOL_LIST } from "./use_tools.js";

/**
 * 服务基础配置
 * @property {string} name - 服务标识名称
 * @property {string} version - 语义化版本号
 * @property {Object} capabilities - 服务能力声明
 */
const SERVER_INFO = {
    name: "ruoxing-mcp-server",    // 服务实例名称
    version: "1.0.0",           // 遵循semver规范
    capabilities: {             // 能力声明
        resources: {},          // 资源预留字段
        tools: {},               // 工具预留字段
    },
};

/**
 * MCP服务实例生成器
 * @returns {McpServer} 已装载工具的服务实例
 *
 * 典型生命周期：
 * 1. 实例化McpServer核心类
 * 2. 装载预定义工具集
 * 3. 返回可操作实例
 */
export const generateMcpServer = (): McpServer => {
    // 初始化服务核心实例
    const server = new McpServer(SERVER_INFO);

    // 装载工具模块
    registerMCPServerTools(server, TOOL_LIST);

    return server;
}

/**
 * 工具注册器
 * @param {McpServer} server - 目标服务实例
 * @param {MCPToolInterface[]} toolsList - 工具配置数组
 *
 * 注册过程说明：
 * 1. 遍历工具配置数组
 * 2. 调用server.tool()注册每个工具
 * 3. 绑定名称、描述、参数和回调函数
 */
const registerMCPServerTools = (
    server: McpServer,
    toolsList: Array<MCPToolInterface>
) => {
    toolsList.forEach(tool => {
        server.tool(
            tool.name,          // 工具唯一标识符
            tool.description,   // 自然语言功能描述
            tool.prams,         // Zod参数校验配置
            tool.cb             // 核心业务逻辑函数
        );
    });
}